feat(cli): add appkit doctor command - #489

Match the capitalized "Details:" label used in the rendered report.

Signed-off-by: Galymzhan <zhangazy2004@gmail.com>

…port

Extend `appkit doctor` to understand Databricks Asset Bundles and to
render a cleaner, single-list report.

- Classify each resource's provenance from databricks.yml + app.yaml
  (bundle.ts): external (probed live) vs bundle-managed (created on
  deploy, reported as such rather than a false NOT_FOUND).
- Add an offline three-file wiring check (checks-wiring.ts) that spans
  app.yaml <-> databricks.yml <-> plugin env vars, catching gaps the
  official validators miss: VALUEFROM_UNBOUND, BUNDLE_REF_MISSING, and
  ENV_UNWIRED. A wiring error gates the exit code for pre-deploy CI.
- Filter to plugins marked requiredByTemplate: true.
- Redesign the report: one flat, severity-sorted checklist (no titled
  sub-sections), every row sharing one shape (glyph + label, indented
  detail, hint set off by blank lines). Reserve colour for actionable
  tokens (cyan ids/code spans, bold env vars) via picocolors, which
  auto-disables for non-TTY / NO_COLOR.
- Shorten and standardise error messages: drop redundant snake_case
  types and SDK noise, quote the value you'd act on, and give missing
  env vars an actionable hint.
- Add --env-file and --detail flags.

Signed-off-by: Galymzhan <zhangazy2004@gmail.com>

CI forces colour on, so picocolors wraps the summary line in escape
codes; the exact-match and startsWith assertions failed against
`\x1b[32m3 ok\x1b[39m`. Strip ANSI in the capture helper so assertions
are colour-agnostic in any environment.

Signed-off-by: Galymzhan <zhangazy2004@gmail.com>

…L, drop --manifest

Act on code-review findings for the doctor command:

- Declare js-yaml + @types/js-yaml in shared's package.json. bundle.ts
  imported js-yaml but only resolved via pnpm hoisting / being bundled
  into appkit — a fragile packaging gap. Declare it like dotenv/picocolors.
- Surface malformed bundle YAML instead of swallowing it. readYaml now
  throws on a present-but-unparseable databricks.yml/app.yaml rather than
  returning null (which set present:false, skipping all wiring checks and
  reporting a false all-clear on deploy-breaking config). Absent files
  still degrade gracefully.
- Remove the --manifest flag. Multiple plugin manifests is a non-scenario
  (appkit.plugins.json is generated at a fixed path), and the flag opened
  two footguns: a mistyped path silently checked nothing, and it could
  desync from the fixed bundle-file paths. Dropping it closes both.
- Document the known limitation that used non-GA plugins aren't checked
  (plugin sync strips requiredByTemplate for non-GA), with a fast-follow
  note, in both the filter comment and the README.
- Comment the deliberate, unrestored process.env mutation in
  getServiceClient (safe in a one-shot CLI).

Adds tests for the malformed-YAML throw.

Signed-off-by: Galymzhan <zhangazy2004@gmail.com>

…tion

The prior code set process.env.DATABRICKS_CONFIG_PROFILE to apply an
explicit --profile — a hidden, unrestored global side effect. The SDK's
own Config exposes a first-class `profile` field, so pass it straight
into new WorkspaceClient({ profile }) instead. No env mutation, no leak
past the call, and it correctly overrides an ambient
DATABRICKS_CONFIG_PROFILE. Verified against the real SDK.

Signed-off-by: Galymzhan <zhangazy2004@gmail.com>

Address a security finding: sensitive data could reach captured output.

- Strip URL userinfo (user:pass@) from DATABRICKS_HOST at capture, so
  credentials embedded in the host never reach the report or --json.
  Validation still runs on the raw value.
- Gate auth.raw in --json behind --detail, matching the human report.
  A bare --json omits the raw SDK error (CI commonly captures --json);
  --json --detail opts back in.

Also folds in pending doctor cleanups the tree already carried and that
these changes build on: an errorMessage() helper in a new utils.ts, and
STATUS_SEVERITY / AUTH_UNAVAILABLE_CODE constants shared via types.ts to
stop run.ts and report.ts drifting.

Adds tests for host sanitization and the --json raw gate (92 total).

Signed-off-by: Galymzhan <zhangazy2004@gmail.com>

ENV_UNWIRED was always a warning, but exitCodeFor gates only on errors —
so a required plugin's env var with no app.yaml entry (set locally via
.env, unset in the deployed container) exited 0, the exact
works-locally-breaks-on-deploy case the wiring check exists to catch.

Gate on target.required: error for required (fails the exit code, blocks
pre-deploy CI), warn for optional. Tests cover both.

Signed-off-by: Galymzhan <zhangazy2004@gmail.com>

No probe, currentUser.me(), or Lakebase SELECT 1 had a deadline, so a
reachable-but-unresponsive endpoint would hang doctor forever — and as a
CI gate, the job would never return.

Add withTimeout (Promise.race against a 10s wall-clock deadline) around
each existence probe and the auth me() call. It can't cancel the
underlying request, but it stops doctor *waiting* so the report returns:
a timed-out probe becomes a PROBE_TIMEOUT error row, a timed-out auth
becomes an auth failure. The timer is always cleared, so a fast result
leaves nothing pending and the CLI exits promptly.

Lakebase connection setup was already bounded (connectionTimeoutMillis:
10s); this covers a hung query on an established connection too.

Tests: withTimeout unit tests (fake timers), a hung-probe run test, and
a hung-auth test.

Signed-off-by: Galymzhan <zhangazy2004@gmail.com>

summary counted only resources; printReport folded auth + wiring in at
render time but never wrote it back, so printReportJson emitted the
unfolded counts. A --json consumer reading summary.error === 0 missed
auth failures and wiring errors (e.g. a required ENV_UNWIRED) — the exact
CI-gate case.

Build summary over everything with a status (resources + auth + wiring)
once in runDoctor, and add a top-level exitCode as the unambiguous
pass/fail signal. printReport now renders the summary verbatim (no
re-folding, so human and --json agree) and exitCodeFor just reads the
field. Moves the aggregation coverage to run.test.ts.

Signed-off-by: Galymzhan <zhangazy2004@gmail.com>

The probe's own .catch covered a probe rejection, but checkResource had
no top-level guard: an unexpected throw (a config-layer error, a
synchronous throw in probe dispatch, anything else) rejected Promise.all
and lost the entire report to a stack trace.

Wrap each resource in checkResourceSafe, mapping any throw to a
PROBE_EXCEPTION error row so the run always resolves and the rest of the
report survives. Test verifies a synchronous probe throw becomes a row
rather than crashing (confirmed it fails without the guard).

Signed-off-by: Galymzhan <zhangazy2004@gmail.com>

The Lakebase pool's default error-only logger dumps the raw SDK ApiError
(stack + full response blob) to stderr on a failed token fetch, burying
doctor's clean one-line classification. Pass logger: { error: false } so
doctor owns the failure output. Reorder createLakebasePool so a
caller-supplied logger overrides the appkit default.

Also trims the Lakebase auth hint and prunes redundant tests.

Signed-off-by: Galymzhan <zhangazy2004@gmail.com>

- checkConfig is synchronous (no async work); update its call site.
- Drop the trivial exitCodeFor wrapper; read report.exitCode directly.
- validateHost drops a redundant placeholder branch (!hasRealLabel covers it).
- Prune tests made obsolete by the above.

Signed-off-by: Galymzhan <zhangazy2004@gmail.com>